Documentation Improvements

[Stephen McDonald]

Hi guys,

Just been having a conversation with Vince Manapat about improvements to the documentation and we thought it would be a good idea to bring the conversation here so that others can add their input.

We were just talking about where the docs can be improved in general, here were my comments:

There are a lot of undocumented features in Mezzanine - the hardest part is how to organise everything logically. 

Take the blog, forms, and galleries apps - these are all undocumented. I don't know what documentation for them might look like. They're not really extendable, they just sit there as features for the end-users (eg not the programmer).

There are also lots of utilities that are undocumented such as template tags and things that live in mezzanine.utils. These could probably use more thorough docs, but they're all heavily commented in the code and so that at least comes out in the auto-generated parts of the docs (http://mezzanine.jupo.org/docs/packages.html), which is partly why they're not documented further.

Another area is mezzanine.generic - this implements reusable types of data such as threaded comments, keywords, and ratings. Maybe a good new section could be for it. Not sure what it would be called, maybe "Generic Data" or "Aggregate Data", that just walks through how to use each of these types of data - covering the fields they expose for models, and the template tags for rendering them.

--
Stephen McDonald
http://jupo.org

[VinceM]

I think one that would be helpful is an example of something you consider to be good documentation to use as a kind of template, whether from the Mezzanine project or elsewhere.

I'm going to be buried in /blog/management/base.py for a while since I have to import an old, frameworkless site into Mezzanine, but as I get more acquainted over the next couple weeks I'll take the subjects here as starting points and pitch in on the documentation.

[Stephen McDonald]

Yeah definitely. For me the Django docs are the shining example. Here are some points I think they follow, and I've tried to follow with our docs, even though they fall short sometimes:

- Use a logical flow. From the overall order of all sections, down to inside each section itself. Things should build up from previous info in the docs sequentially and not assume any knowledge without having covered it first. Think about the order of the steps someone might take when using the software, and try document things in the same order.

- Solve a problem. Each section or sub-section should solve a problem. Here's a problem, here's a feature that can solve it, here's how to use it.

- Be clean. Just like writing Python where readability for other programmers is a primary concern. Treat the docs like code and refactor them until they're as simple as can be, without leaving anything out. Over the last few years I've found I can improve my writing by applying the same principles to it as I do to coding.

- Try and tell a story. Talk to the reader instead of just dumping info out.

As a side note the blog importing features have their own docs section in case you missed it, so it sounds like that might be a good starting point to chip away at: http://mezzanine.jupo.org/docs/blog-importing.html

[carlos]

Hi all

I think the best way is to make a tutorial on getting started with mezzanine as the official website of installation with pip and creation of the project. but there is still a small tutorial on how to modify the template, and add the new app to appear on the main menu, something like the tutotial that is in the official Django site :) but for mezzanine

regards

Carlos Rocha

[Stephen McDonald]

Great idea. Perhaps it could form a section called Quick Start Guide or something. What steps should it go through?

- Installation

- Create a page content type

- Create a template for it

- Create an admin class for it

- Add a blog field and its admin class (to demo EXTRA_MODEL_FIELDS)

- Modify the base template + css

- Deploy

I guess each of these should be fairly concise and finish with a link to their relevant sections in the existing docs.

[Josh Cartmell]

Would it make sense to have a developer's quick start and an administrator's quick start?

I would think of what you described as the developer's quick start.  The administrator's quick start could be something like:

- Add a RichTextPage
  - Add an image to the Media Library and put it in the richtext page
  - Discuss the draft/published differentiation and the published from and expires on options
- Customize the default contact form by adding a field. (or maybe add a new form)
- Show how to make a blog post and categorize it
- Explain comments and moderation (if applicable)
- Explain why the home page may not be editable in the admin (historically this has raised a number of questions among developers on this list, so I think admin users may wonder the same)
- Show how you can edit the site title and tagline through the admin

Obviously a lot of this stuff sounds pretty trivial but I think it would be a nice reference to have to give to people.  It could also help demo Mezzanine to potential clients by giving them an easy way to get their feet wet.

As for the developer guide outlined earlier, would we want to show how to make a page processor, possibly for the content type created?

[Stephen McDonald]

Having docs for admin users would be great. I don't think it's trivial if you consider the target audience. The only problem is that once you start adding custom content types or new models in general, then those docs become out of date. I don't think this is a reason not to do it though, but it's a good starting point for thinking about how these admin docs might be extendable by the developer to include their own customizations.

[Josh Cartmell]

This is a little bit of thread necro but would I was thinking it would be nice to have documentation explaining basic South usage with Mezzanine.  I know it is a bit outside the scope of Mezzanine but it could be a nice reference to have when upgrading from a previous version of Mezzanine.

That made me think of a question regarding South and Mezzanine, if you skip versions of Mezzanine will you still be able to migrate or do you have to hit every version in between?

[Stephen McDonald]

I think this is a good idea for the docs.

Skipping versions shouldn't matter - the south history DB table will know which migration you're at, and when you install the latest version, you'll get all the new migration files, potentially spanning multiple versions. When you run migrate next, it'll pick all these up. The Mezzanine version and the migrations aren't really related.