>Message: 5 >Date: Sat, 07 Mar 2009 21:33:20 +0100 >From: Rainer M?ller <[email protected]> >Subject: Re: The Guide - again >To: Ryan Schmidt <[email protected]> >Cc: MacPorts Development <[email protected]> >Message-ID: <[email protected]> >Content-Type: text/plain; charset=ISO-8859-1 > >Ryan Schmidt wrote: >> I do not believe that we need to separate these into different >> documents because there is overlap between these different peoples' >> needs. We could do a better job of indicating which sections are for >> which audience, or rearranging sections in the guide to group things >> by audience.
Hi Ranier, I think the distinction between types of users for documentation is problematic. But chunking documents into "topics" and assembling them into various docs as needed would at least allow it in theory. It is called DITA. Another XML standard. I know, ugh. But I just don't see how we can ditch XML and still do what we need to do. http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture But the guide is not complete yet. This summer I intend to make a final push to do it. Of course it will never be finished, but the big missing pieces can be filled in, and then sourcing the man pages out of it can happen. > >I don't like the fact that the guide is one huge document. We discussed >splitting the guide into single pages ('chunked' in docbook terms) >before, but the majority was against it. In my opinion it would at least >make sense to split the guide into pages each of them relevant for >users, maintainers, base hackers. > >There is the MacPorts Internals documentation (API, registry etc.) which >is not interesting for anyone else than base hackers. Maybe it should >not be in the guide at all, but live in the repository as plain text only. As Ryan mentioned, there is the chunked version. It could be that the internals section and the project section doesn't belong, and I think after finishing the major parts this summer we could discuss that as a "where do we want our docs to go now" discussion. > >> I do not believe we need to move all or part of the guide to the >> wiki. Quite the opposite: documentation that's getting created in the >> wiki should get moved to the guide. > >To be honest, editing the guide sucks. Contributing to the wiki is much >easier. > >Especially if the concern is the guide being outdated, I see the problem >in the guide format. We had the recent discussion to move the guide to >another markup language but it was teared down. What else can we do to >attract more people for writing documentation? But if we have more than a few people contributing anything other than incremental changes, we'd need to use the formal approval process we've already talked about. So I don't see how that solves anything. There is a natural tendency for people to throw all kinds of stuff into documents just because they can. I use text files in Textedit to flesh out documents and document structure so I don't understand why this is not acceptable to do this or any other technique and post it for review. Contributions don't need to be in XML. Mark _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
