Understanding documentation

Hi Doc team

I would like to share with our a very interesting reading I found on
documentation and its companion presentation.

What Nobody Tells about Documentation
https://www.divio.com/blog/documentation/

Video
https://www.youtube.com/watch?v=t4vKPhjcMZg

To sumarize it on the contents, it deals with the several kinds of
documentation.

<quote>

There is a secret that needs to be understood in order to write good
software documentation: there isn’t one thing called documentation,
there are four.

They are: tutorials, how-to guides, explanation and technical reference.
They represent four different purposes or functions, and require four
different approaches to their creation. Understanding the implications
of this will help improve most software documentation - often immensely.

</quote>

regards

Thank you Olivier, a very interesting read. You and I discussed
something similar at a docs meeting sometime ago, when we talked about
adding links in the guides and Help files to FAQs, HowTos & Tutorials.

Unfortunately, Daniele Procida (the author of the article) made one
glaringly serious omission, when he writes "There isn’t one thing called
documentation, there are four." he totally overlooks and consequently
offers no solution to the Fifth and critically important thing "Numbers
of People to do the Other Four".

Sorry to sound a negative note, but I am weary of experts saying how
things should/could be done, without offering a solution to the main
problem of finding the contributor numbers to do those things. We
already have in place much of what Daniele recommends, but we just don't
have the numbers of contributors to take them forward.

Regards
Dave

He totally overlooks and consequently offers no solution to the Fifth and critically important thing "Numbers of People to do the Other Four".

Daniel is coming at it, from the perspective of a project manager.
* Get the requirements for the Project;
* Break the Project into Activities;
* Break the Activities into Work-Packages;
* Break each Work-Package into Units;
* Break each Unit into specific tasks;
* Assign one team to each Work-Package;

In this specific case, "Documentation" is the Project:
The Activities are:
* Tutorials;
* How-to guides;
* Explanation;
* Technical Reference;

In publishing (^2), historically (^1) the Units are:
* Proposal;
* First Draft;
* Developmental Editing;
* Second Draft;
* Copy Editing;
* Third Draft;
* Line Editing;
* Fourth Draft;
* Proof Reading;
* Fifth Draft;
* Grammar Checking;
* Sixth Draft;
* Art Work: Interior, Exterior, Marketing;
* Seventh Draft;
* Fact Checking
* Eight Draft;
* Indexing;
* Ninth Draft;
* Back Matter & Front Matter;
* Tenth Draft;
* Review Editing;
* Galley Proof;
* Publish;

I'm not going to break each Activity into Work-Product (^3). Nor am I
going to break each Unit into specific tasks;

Historically, publishers rotate indexers, illustrators, and cover
designers between books. The editors usually stay with a book for the
entire process. The writer always stays with the book.

So, to answer the question. 4 teams, with however many writers, editors,
etc. as are available, and needed. However, "team" here is used very
loosely. The indexers, illustrators, and cover designers will rotate
between the four activities, and as such, might not be considered to be
part of the team, by the editors and writer of a specific team.

Historically, publishers have used a team of between 5 and 10 people, to
put together one book. This team size includes only people who were with
the book from conception to publication. It excludes the rotators --
indexers, artists, etc.

problem of finding the contributor numbers to do those things.

The number of contributors, and how to obtain them, is a different
issue, and thus off-point, for that specific article.

https://github.com/freeCodeCamp/how-to-contribute-to-open-source
containers pointers to attracting more contributors to your project.
The big takeaway is that it is about community:
* Respect the contributors;
* Acknowledge contribution;
* Gently correct specific issues within a specific contribution;

We already have in place much of what Daniele recommends, but we just

don't have the numbers of contributors to take them forward.

I don't have any evidence, or data to support the following:

A person looks at the possible things that they con do, to contribute,
and feels overwhelmed. There are so many possibilities, that their brain
figuratively shuts down.
https://documentation.libreoffice.org/en/join-the-documentation-team/
has six choices. But then click on the first choice,
https://documentation.libreoffice.org/en/join-the-documentation-team/update-help-contents/
then on the first link on that page, and you end up at
https://bugs.documentfoundation.org/showdependencytree.cgi?id=80430&hide_resolved=1
which has 50 things to write a help page. Click on the first bug and
https://bugs.documentfoundation.org/show_bug.cgi?id=71154 comes up.
What's an RSID? bye-bye, I'm out of here.

Let's say you make it to
https://documentation.libreoffice.org/en/join-the-documentation-team/i-want-to-write-technical-books/
(Yikes. That page needs both a proof-reader, and a grammar checker. (Is
it supposed to be en_US, en_CA, en_NZ, en_ZA, en_GB, en_AU, or en_SG?
Regardless, it is a mix of the above.)

The call to action, is to subscribe to the list.
So what happens once the potential contributor subscribes to the list?

^1: For Lulu & Smashwords, the sequence is "write, add art work, upload,
market". For Kindle Select, the sequence is "write, add art work,
format the material, upload, market". The only changes the Big Five make
are requiring a proposal, and sending in a managing editor who may, but
probably won't require any other editing.

^2: Each book is a Work-Product;

^3: The number of "How to do x" manuals for LibO is, in essence,
infinite. I don't think that "How to play Tick, Tack, Toe with
LibreOffice" is useful. Humorous, but not useful. OTOH, that would make
for an interesting release on 1 April 2020. (I don't remember if
Logo4LibreOffice is Turing-Complete. R is, but setting up R as an
internal macro-language for LibreOffice is probably beyond the skill set
of most LibO users.)

jonathon

Hi Dave,

the article Olivier has pointed out is very interesting in that it clearly states what many documentation writers know without contextualizing it.

[...]
Sorry to sound a negative note, but I am weary of experts saying how
things should/could be done, without offering a solution to the main
problem of finding the contributor numbers to do those things. We
already have in place much of what Daniele recommends, but we just don't
have the numbers of contributors to take them forward.

I think Daniele's point isn't about contributors but about documentation as an asset, thus no surprise he doesn't mention the question you're rightly pointing.

Best regards,