Bazaar All Docs Website

How do I contribute to the documentation?

Asked by Zearin

I'm not knowledgeable enough about “real” coding to help with the project itself. But I am good with (X)HTML, CSS, and improving documentation in terms of phrasing, clarity, and formatting for readability.

I know the documentation is written in Sphinx, which is fine. It's a pleasant enough shorthand for most HTML stuff. :)

I got a local branch of the Bazaar All Docs Website trunk, but I can't seem to find where the actual DOCUMENTS are stored. I see a bunch of configuration, but all I want to do is help do some basic edits to make the documentation better and I can't even figure out where to get started. :(

Little help?

Question information

Language:
English Edit question
Status:
Solved
For:
Bazaar All Docs Website Edit question
Assignee:
No assignee Edit question
Solved by:
Martin Pool
Solved:
Last query:
Last reply:
Revision history for this message
Zearin (zearin) said : 		#1

Anybody?

Revision history for this message
Martin Pool (mbp) said : 		#2

Which specific document are you looking for?

The plugin guide is mostly generated from metadata is the plugins pointed to by plugins-registry.ini, plus the content in plugins/en of the bzr-alldocs tree.

The per-bzr-release documents are stored in ./doc in the relevant bzr branch.

Please ask if you have more questions; I'd really like to help you improve the bzr docs.

Revision history for this message
Zearin (zearin) said : 		#3

Life gone crazy—actually make that “crazier than normal”. Sorry for slow reply!
***
Wow, the documentation lives all over the place! :) But I'm pretty sure that what I want is the per-bzr-release documents. That is, if you goto http://doc.bazaar.canonical.com/en/ and click on the “HTML Online” documentation for the current version of Bazaar, I'm talking about the documentation in there.

Yeah, I know that technically takes you to a bunch of different documentations. I do peruse them all from time to time. I suppose if I had to pick one to start with, it would be

• the “User Guide”, followed very closely by
• the “User Reference” and
• the “Bazaar Explorer” guide (seems to be somewhat more separated compared to the other guides)

…

I'm chiefly interested in fixing (in no particular order):

• Phrasing and wording for clarity
• Grammar, punctuation nitpicks
• Standards-based markup and CSS
• A prettier design for the HTML documents in general

I know those last two are primarily auto-generated by Sphinx. But OTOH I loves me some XSLT and I'm growing more comfortable with XProc, which could possibly just take the existing generated files and do some transformations or something.

…

But since life's been crazy lately I think just tweaking the documentation text itself is the more low-hanging fruit. So that's where I think I'd be doing most initial contributions.

So, um…how do I get the appropriate files? :D

Revision history for this message
Best Martin Pool (mbp) said : 		#4

Hi there,

The source text files for this documentation is mostly in the bzr
source tree (under doc/).

See the 'contributor quickstart guide' in the developer documentation
for how to get that and how to proposed changes.

Good luck!

Revision history for this message
Zearin (zearin) said : 		#5

Oh! Yes, there they are. Thank you!

(So, as a quick side note, it seems to me that the name of the bzr-alldocs project is misleading. It's not really ALL the docs…)

I already know a few easy changes I can make just to commit something and establish credibility. I'm going to read up on the official process for this in the documentation now, and I'll open separate questions on Launchpad if I have any.

Once again, thanks so much. I'm looking forward to finally being able to contribute for the first time to this project. :)

Revision history for this message
Zearin (zearin) said : 		#6

Thanks Martin Pool, that solved my question.

Revision history for this message
Zearin (zearin) said : 		#7

Okay, so I've got a personal branch up where I will be making text-only edits to the Bazaar documentation. The branch is here:

lp:~zearin/bzr/docs-textedits

I've been following Launchpad and Bazaar on and off for a couple of years now, but this is the first time I'm actually participating in a project (*geek-joy!*). So my apologies in advance for any missteps of procedure.

Actually participating is so very different from just observing. :)

Revision history for this message
Martin Pool (mbp) said : 		#8

Hi,

Hope this is working out well for you.

I see you made a first commit on this branch which was apparently just a merge of trunk. If you haven't made any changes yet, it's cleaner just to run 'bzr pull lp:bzr'.

As soon as you get some changes, even if it's just making one paragraph clearer, don't hesitate to commit and push up your changes, and ask for them to be merged.