[Nix-dev] Real documentation, aka "Let's kill the wiki"

[Domen Kožar]

You have to think about the audience.

In general following should cover us:

- tutorial (how do I get quickly update to date on X topic)
- user guide (how does a specific feature work)
- reference (functions and what they do)

Currently that's all bundled throughout the manual (and wiki).

Domen

On Wed, Nov 18, 2015 at 5:01 PM, Karsten Gebbert <k at ioctl.it> wrote:

> Hajo Möller <dasjoe at gmail.com> writes:
>
> > As mentioned in another thread, Rok Garbas proposed to remove the wiki
> > and replace it with "real documentation". I fully support this.
> >
> > To follow up on this proposal I suggest we decide what real
> > documentation should look like, so let us reiterate his main points:
> >
> > "Why do we write documentation?"
> > Is it just to remind ourselves about details, or also for helping the
> > readers reach an advanced level of understanding? It should be the both.
> >
> > "There needs to be a clear definition of how documentation is written."
> > We already have coding conventions, but there is no clear how-to for
> > writing good documentation. Maybe (professional) technical writers can
> > chime in here?
> >
> > "Documentation should teach, not tell."
> > As Rok said, handing somebody who is learning a new language a
> > dictionary would not help them learn.
> > It is not possible for us to get an immediate reaction to pinpoint the
> > exact moment our documentation becomes incomprehensible, having our
> > documentation follow a well-defined pattern should help here.
> > This also means we need to hold our users' hands, leading them
> > step-by-step through complex procedures instead of directly presenting
> > results.
> >
> > "You should never tell somebody to read the source."
> > Even though the source code should be self-explanatory (and often is,
> > see the files in nixpkgs/lib for well-commented examples), having real
> > documentation in the form of a manual helps keep everything in the same
> > place. This way there can be a single location where users come to when
> > they are lost.
> >
> > "The manual is good, but not made for beginners."
> > Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> > Although I generally agree, I am not sure where to place those tutorials
> > and what they should cover. Should they be on people's blogs, aggregated
> > in the planet.nixos.org?
> >
> > "Let's kill the wiki, it's not documentation but an abomination."
> > Unmoderated wikis tend to contain outdated or just plain wrong
> > information, it is then arguably better to have no documentation at all
> > than a wiki teaching the wrong things. Also, developers asking (possibly
> > misunderstanding) users to fix the wiki could lead to a scenario where
> > the blind lead the blind.
>
> I think that it would be good to loosely decide on the sections a good
> manual/documentation should consist of. This might help structuring the
> effort
> and break up tasks in meaningful chunks.
>
> I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind
> of),
> and it would be good to approach the task with its quality and
> comprehensiveness
> as the long-term goal.
>
> From the top of my head, there are multiple aspects to it:
>
> * Cookbook (how do I do XYZ?) e.g.
>   - setting up a Desktop environment
>   - setting up ...
>   - setting up a development environment
>   - detailed guides on developing with in language XYZ
>   - overriding/customizing packages
>   - ....
> * nix-* command reference (man pages would probably already suffice)
> * nixpkgs & library (w/ inline docs)
>   - modules
>   - contributors guide
>   - function reference?
> * nix, the language
>   - reference manual
>   - useful snippets?
>
> So, if there is an effort to aggregate information in one place, we could
> split
> up the task according to such a list of sections and work more or less
> independently in branches.
>
> Best,
>
> karsten
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20151118/61ecc2ef/attachment.html