Documentation overhaul

[Rainer Müller]

On 2016-10-10 01:23, Ryan Schmidt wrote:
> Thanks for your interest, Marcel, but do you feel you would be able
> to lead such an effort, since you seem to be new to MacPorts? I've
> been with MacPorts for around 10 years and have thought of rewriting
> the documentation for several years so I feel I might be able to do
> it. I'm just not doing it right this second because I'm busy trying
> to move us to new hosting. And also because we don't yet know how how
> we will work on GitHub, so we can't fully document that yet.

Our documentation has been in a dire state for years now. As I mentioned
before, the new help system was started by me about 7 years ago. Even
back then we were already discussing to convert/rewrite the guide. Not
much has changed since then.

Most of the time the man page project was in limbo because nobody was
writing the actual man pages. I also lost motivation after a while and
eventually Clemens picked it up and finished it.

Now here is Marcel offering his help with the documentation. I do not
want to turn down his offer or stop him from contributing in any way.

I do not think a lot of experience is required to write good
documentation. Especially when we are talking about reorganizing the
existing documents. Being only a user could help to write the
documentation from the view of a user without diving too deep into
internals.

Moving away from Docbook, converting the existing content or evaluating
other tools would be a lot of work that could be done by anyone.

> My plan is to read all documentation, maybe even print it all out on
> paper (guide, wiki, web site), cut it up, group related information
> together, remove duplication (like the three different sets of
> install documentation we currently have), remove superfluous
> language, simplify, and also add new documentation for things that
> currently aren't documented, like newer portgroups. Also review the
> organization and content of the documentation of other projects that
> I consider well done, such as svnbook.org. If you know of other good
> documentation I should review let me know.

One of the most important steps would be to split the documentation
clearly into:

* Installation
+ MacPorts Quickstart/Cheat Sheet
* Using MacPorts
* Writing Portfiles
* Contributing
+ List of Terms/Glossary
* Management Policies
* Internals for base Developers

  * = already exists
  + = needs to be written

Overall:
make it more concise, less text, examples instead of explanations.

Maybe split installation instructions by macOS versions so users only
see relevant instructions.

It would also be good to have some conditionals to mark
paragraphs/sections by version. Then we could write documentation for
trunk while the website keeps displaying the stable versions (or let you
choose).

To me, svnbook.org is old, outdated and the HTML version on the web
definitely does not feel modern.

> My plan is to do this after redoing the web site. I intend to keep
> the installation instructions that have to do with the default
> installation using the macOS Installer on the web site, so rewriting
> that will be a good beginning to rewriting the documentation.

I know you have been working on the new website for quite a while. But
you also do the buildbot and other management related tasks. I would
even say chances are high that this will be delayed further...

If Marcel has time right now, I think he should just start with the
documentation.

Rainer