Gotcha, thanks for the advice. I'll be updating the wiki docs with the over-ruling guideline to keep code simple and readable, but also list a few ways in which to keep the code more consistent. These extra guidelines should be totally optional (to avoid, as you said, over-legislating the coding), but available for those who wish to follow them. Thanks again!
On Sat, Dec 18, 2010 at 9:38 AM, Phil Bull <[email protected]> wrote: > Hi Daniel, > > Great to hear you're working on the gedit docs! Please let us know if > you need any help with the conversion - reworking a manual into > topic-based help can become quite an involved process. > > On Fri, 2010-12-17 at 21:31 -0500, Daniel Neel wrote: > > Hello all, I wanted to send a note asking for recommendations about > > coding guidelines for the Mallard conversion of gedit docs. I'm > > assuming that one rule that can be established is that tags should be > > nested. > > Yes, that's definitely a sensible policy. You'll probably find it > difficult to get people to stick to a 2-space indent policy, but that > shouldn't matter too much. The main thing is that it's easy to read the > markup. > > > So I'm going to update the wiki with this suggestion and implement > > this in the code. Please tell me if another method would be better - > > this one seems obvious enough to go ahead and implement though. > > You can use a tool like "tidy" to automatically do this for you. It has > an XML mode. > > > Can anyone think of any other guidelines that would be helpful for > > writing the docs? Two that I can think of are: > > > > How many spaces to put at the end of a self-closing tag. IE: <tag1/> > > or <tag1 /> ? I vote for the second as the tag's information seems a > > bit less cluttered and easier to read. > > This is reasonable (I normally go for the latter). > > > And how should Mallard's <revision> tag be used? My vote goes to the > > following format: > [...] > > > This way, each revision of the document is visually grouped with the > > author who revised it. The revision tags should only be used on > > medium-sized+ contributions. Adding 5 lines of text to the file for > > each change would be a headache. > > > Or is it even worth using the <revision> and <credit> tags, since git > > keeps track of the code's revision history regardless? It could be > > nice to have a quick overview of how development of the document > > proceeded, but that might also clutter the document a bit. > > I've been using one revision tag and however many credit tags for each > topic. The credit tags are useful for keeping track of copyright when > the files are distributed, but (as you said) with git it's not necessary > to keep multiple revision tags. > > > Otherwise there doesn't seem to be a whole lot that can be specified > > for writing in Mallard (that I know of at least). Thoughts anyone? Am > > I over-thinking this? > > Defining a few basic guidelines can be a good idea, but don't go > overboard! If you try to legislate coding style too much it becomes a > pain for reviewers and contributors. I'm a fan of using broader guiding > principles instead - in this case it would be "keep it readable"! > > Thanks, > > Phil > >
_______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
