5 ms·

What if we put community energy into contributing improvements to existing man pages for open source projects? As many commenters have noted, it is possible to

by mch82 11y ago

What if we put community energy into contributing improvements to existing man pages for open source projects? As many commenters have noted, it is possible to accomplish the goals of TLDR by improving existing man pages, without establishing a separate documentation system. A man page can be formatted to include any number of sections. All that is needed is an EXAMPLES section that lists examples for typical command usage. Here are instructions for creating a man page: http://www.schweikhardt.net/man_page_howto.html#q3 http://www.schweikhardt.net/man_page_howto.html#q3 Side note... isn't the usage of TL;DR in this project incorrect? TL;DR is a synonym for "abstract", "synopsis", and "executive summary". It is already confusing enough to use TL;DR in place of those words without overloading the term to mean "tasks", "example usage", or "typical use cases".

falsedan 11y ago
Historical man pages have been the comprehensive reference for a command. You can't write a document that serves both as a gentle introduction to a tool for a new user, and retain the encyclopedic list of every possible option. Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.
- mch82 11y ago
  For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "journalism", and "introductions" summarize "books". People understand how to use these conventions. How is it easier for the end user to have to learn to install, use, and understand an additional tool chain? How is it easier for a project maintainer to manage documentation in multiple locations? https://xkcd.com/1319/ https://xkcd.com/1319/
  - falsedan 11y ago
    It's not easy? It's hard to write documentation that's suited for reference AND expert users AND new users. All of the materials you mentioned are for informing/entertaining people, not training them to acquire new skills. There is a field of study specifically for this: education. Also, be less patronising.
    - mch82 11y ago
      I guess that for me the git man page does it's job as the quick summary for how that program works and git-scm.com/book is the training tool I rely on as a new user. There is so much to learn that a man page cannot concisely cover, like how to structure a collaborative workflow in a distributed team. For that, turning to a well written book has been key. I'm definitely not suggesting that writing useful documentation is easy. I agree with you that it takes work to write documentation and training material that people can use. Not my intent for the prior post to be patronizing. Sorry it came across that way.
kevan 11y ago
Projects like this happen because it's easier to contribute here than to the existing manpages. As someone who came of age in a Github world, there's (perceived) friction preventing me from trying to contribute to a lot of tools from the old guard. Let's say I want to add some examples to the tar man page: * How do I create a man page? (you answered this one) * Where is the vcs repo for tar? (I think it's this one git.savannah.gnu.org/tar.git) * I cloned the repo, but I don't see a contributing guide. Looks like I need to create an account and submit a patch online? * Do I need to let the mailing list know about it? How do code reviews work? None of these steps are dealbreakers, but together it all adds up to more unknowns I need to figure out before I can contribute. If existing projects make their contributing process smoother then I think we'll see more of this effort go directly to them.
- masukomi 11y ago
  agreed 100% when all you want to do is make a small tweak to some text spend literally hours trying to figure all that out just isn't worth it. Better to say "fuck it" and move on.
- mch82 11y ago
  The friction you feel likely is more than just perceived. Perseverance can often break past it and sometimes a disruptive spinoff proves to be required. I work at a company where the typical employee is 20-30 years older than I am. It is often a struggle to get people to adapt to change, the key is to persevere. As an example, I just finished participating in a 4-year effort to get my organization to adopt Git! Often, projects like TLDR are necessary as proofs of concept to help the old guard understand the value of an idea or initiative. Even something as simple as this discussion existing might help people see an unmet need or expectation exists. And sometimes, when the old guard fails to respond, it is worth spinning those projects off with a group who sees the "new way" as clearly as breathing oxygen and replacing the old way of doing things completely. Your list of bullets is a good one. To be honest with you, I've only contributed to open source docs a small number of times, submitting merge requests to Canonical. So, I will give updating a man page a try and see if I can figure it out.

by mch82 11y ago

falsedan 11y ago

Historical man pages have been the comprehensive reference for a command. You can't write a document that serves both as a gentle introduction to a tool for a new user, and retain the encyclopedic list of every possible option. Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.

mch82 11y ago
For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "journalism", and "introductions" summarize "books". People understand how to use these conventions. How is it easier for the end user to have to learn to install, use, and understand an additional tool chain? How is it easier for a project maintainer to manage documentation in multiple locations? https://xkcd.com/1319/ https://xkcd.com/1319/
- falsedan 11y ago
  It's not easy? It's hard to write documentation that's suited for reference AND expert users AND new users. All of the materials you mentioned are for informing/entertaining people, not training them to acquire new skills. There is a field of study specifically for this: education. Also, be less patronising.
  - mch82 11y ago
    I guess that for me the git man page does it's job as the quick summary for how that program works and git-scm.com/book is the training tool I rely on as a new user. There is so much to learn that a man page cannot concisely cover, like how to structure a collaborative workflow in a distributed team. For that, turning to a well written book has been key. I'm definitely not suggesting that writing useful documentation is easy. I agree with you that it takes work to write documentation and training material that people can use. Not my intent for the prior post to be patronizing. Sorry it came across that way.

kevan 11y ago

Projects like this happen because it's easier to contribute here than to the existing manpages. As someone who came of age in a Github world, there's (perceived) friction preventing me from trying to contribute to a lot of tools from the old guard. Let's say I want to add some examples to the tar man page: * How do I create a man page? (you answered this one) * Where is the vcs repo for tar? (I think it's this one git.savannah.gnu.org/tar.git) * I cloned the repo, but I don't see a contributing guide. Looks like I need to create an account and submit a patch online? * Do I need to let the mailing list know about it? How do code reviews work? None of these steps are dealbreakers, but together it all adds up to more unknowns I need to figure out before I can contribute. If existing projects make their contributing process smoother then I think we'll see more of this effort go directly to them.

masukomi 11y ago
agreed 100% when all you want to do is make a small tweak to some text spend literally hours trying to figure all that out just isn't worth it. Better to say "fuck it" and move on.
mch82 11y ago
The friction you feel likely is more than just perceived. Perseverance can often break past it and sometimes a disruptive spinoff proves to be required. I work at a company where the typical employee is 20-30 years older than I am. It is often a struggle to get people to adapt to change, the key is to persevere. As an example, I just finished participating in a 4-year effort to get my organization to adopt Git! Often, projects like TLDR are necessary as proofs of concept to help the old guard understand the value of an idea or initiative. Even something as simple as this discussion existing might help people see an unmet need or expectation exists. And sometimes, when the old guard fails to respond, it is worth spinning those projects off with a group who sees the "new way" as clearly as breathing oxygen and replacing the old way of doing things completely. Your list of bullets is a good one. To be honest with you, I've only contributed to open source docs a small number of times, submitting merge requests to Canonical. So, I will give updating a man page a try and see if I can figure it out.