Documentation overhaul

[Ryan Schmidt]

> On Oct 9, 2016, at 15:23, Rainer Müller <raimue at macports.org> wrote:
> 
> Hello Marcel,
> 
>> On 2016-10-09 15:53, Marcel Bischoff wrote:
>> As Ryan has identified that the online documentation needs work, I'm
>> hereby volunteering to give it a go. Since there appear to be quite
>> specific views on how everthing here needs to be, I'm asking in advance:
>> 
>> - Is that in everyone's interest?
> 
> Of course! :-)

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. 

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. 

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. 


>> - Is there already someone working on it?
> 
> We have a new help system on trunk. Each command has a separate man page
> that can be reached with 'port help install' and similar. Eventually
> these should also end up on on the web, for example at man.macports.org.
> 
> https://trac.macports.org/wiki/NewHelpSystem
> 
> The source of the new man pages can be found in base/doc/*.txt in
> AsciiDoc format:
> 
> https://trac.macports.org/browser/trunk/base/doc
> 
>> - Where should the final documentation be located: separate website,
>> GitHub wiki, GitHub pages, readthedocs.org, something else?
> 
> The best would be to overhaul/replace https:///guide.macports.org with
> something new and better structure.
> 
> The existing guide can be found here:
> https://trac.macports.org/browser/trunk/doc-new
> 
> Hosting the site should be the least concern, we have resources for that
> now.
> 
>> - In what format should the documentation be written: HTML, Markdown,
>> TeX, whatever? I prefer Markdown.
> 
> I think one of the main reasons why nobody likes updating the guide is
> the DocBook XML syntax.
> 

That is my problem, yes. I don't recall why docbook xml was originally chosen, but I would change it now. 


> Back in 2009 (sic!), I started the new help system in AsciiDoc, inspired
> by the git help system. AsciiDoc is more complex than Markdown, but
> supports syntax elements such as includes and macros, that are very
> helpful in reusing the some content in multiple pages and keeping the
> layout consistent. Also, macros can be defined per output device,
> expanding to specific syntax in roff/html/pdf/etc.
> 
> I am fine with using Markdown, as it is the dominant markup syntax
> today. However, it is also very limited, but that might just be enough
> for the guide.

I like markdown but it is missing a lot of things. There is an opinion piece I found online about who you should never try to write documentation using markdown for this reason. 

Based on Rainer's choice to use asciidoc for the new help system, I suggest we convert the guide to asciidoc and use that as the basis for new documentation. I already did a trial conversion of the guide to asciidoc which seemed fine for the page or two I looked at. Asciidoc is hostable on github pages, which is what I will want to do.