News for hackers. Stuff that matters.
Re:Things People Hate about Your Open Source Docs by zdw on Friday June 21, 2013 @11:08AM (#5918389)
Manpages used to be the defacto best source of information, but sometime in the last 15 years they went from great to a hit and miss shambles.

I write this up to GNU's "info" being preferred by some programs, but then that not being installed properly or at all on many system, and people hating manpage syntax, often with good reason.

That said, some systems pay a lot of attention to this. OpenBSD's mandoc is a great example of a modernization of the manpage system, and their manpages are second to none: http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

Re:Things People Hate about Your Open Source Docs by takluyver on Friday June 21, 2013 @12:59PM (#5919290)
I think people now like documentation in lots of different forms - manpages, HTML, pdf, or introspectable docs like Python docstrings. IPython, for example, has all four of those.

There are systems like Sphinx that let you share content between different formats, but they're not magic bullets. For instance, if I write docs relying on inline links because I'm used to viewing them in HTML, the result won't be great for manpage readers.

Re:Things People Hate about Your Open Source Docs by dmckeon on Friday June 21, 2013 @02:02PM (#5919828)
The info nav system can be avoided with:

    info () { command info "$@" 2>&1 | less; }
to get the content with a more (or less) familiar nav tool.

Another useful approach is to 'project the document' rather than to 'document the project'. Write the draft documents as part of the specification and development process. Code the project. Finally, edit the docs to match the code.

You get to capture the state of early energy and an over- or top-down view before diving into the code, and will remember to mention details of the design while they are fresh and new, rather than at the end of the coding process, when everything has become so familiar that it all seems trivially obvious.

Re:Things People Hate about Your Open Source Docs by kyrias on Friday June 21, 2013 @01:05PM (#5919341)
Wait, there's programs that use info? o.O
Re:Things People Hate about Your Open Source Docs by coldpie on Friday June 21, 2013 @01:35PM (#5919611)
Oh yeah. 'man cp' from my Arch Linux machine:

---

SEE ALSO

The full documentation for cp is maintained as a Texinfo manual. If the info and cp programs are properly installed at your site, the command

              info coreutils 'cp invocation'
should give you access to the complete manual.

---

I ran that 'info' command and promptly ran the one emacs command I have memorized: C-x C-c

:)

Re:Things People Hate about Your Open Source Docs by m-r-a-m on Saturday June 22, 2013 @02:30AM (#5922788)
I recently switched to Emacs and started learning it by going through the tutorial (C-h t). Near the end of the tutorial, it refers you to the Emacs manual which uses info (C-h r). After going to the manual I had no idea how to navigate, so I ran the info tutorial (h). I don't really have a point, but I think it's funny that I had to run the a tutorial to get help.
Re:Things People Hate about Your Open Source Docs by kyrias on Saturday June 22, 2013 @07:44AM (#5923267)
Coreutils come from the GNU project so I wouldn't really count it. :p
Re:Things People Hate about Your Open Source Docs by throwaway2048 on Friday June 21, 2013 @04:11PM (#5920692)
the best part is when a man page has an entry like this, and then the info page is a copy of the man page...