Basics

[Bjarni]

Hi everyone.

Is there some place basic concepts in the Armstrong project are
explained. For example, what are Wells, Well Types, Sections etc.,
how they work together, and how they can be used.

Best regards,
Bjarni

[Travis Swicegood]

Hi Bjarni;

Those are a work in progress right now and an area we know we're currently lacking in.  Each of the projects have a readme that gives you some of the background, but not tons.  I'm starting work on unifying those into a cohesive whole to get people started.

With that in mind, it seems like a quick glossary and then some explanations + examples of how to use them would be most helpful...?  Is there anything else you'd like to see as someone new to the project?

-T

--
Travis Swicegood | @tswicegood (most everywhere) | Senior Open Source Engineer @ Texas Tribune / Armstrong | 512.693.7051

[Chuck Taylor]

I'm not a coder but have a lot of experience with CMSes and might be able to lend a hand with documentation. Is there a wiki?

Chuck Taylor
Seattle

chuck....@newsdex.net
Personal page: http://bit.ly/f8DHHK
206-396-1017

Twitter: http://bit.ly/hsCpc4 | Flickr: http://bit.ly/gaG6EW | Blog: http://bit.ly/f0NGf5 | LinkedIn: http://linkd.in/gEyWgi | Where I work: http://www.heraldnet.com/ | View from the newsroom: http://bit.ly/eD167Y

Newsdex Seattle - Social network metrics for media: http://seattle.newsdex.us

[Travis Swicegood]

Hey Chuck,

We do now:

    https://github.com/armstrong/armstrong/wiki/Glossary

Feel free to create new pages or help out on any of the existing ones that are there.  Let's use the wiki as the test bed for docs, then we'll pull them out into proper documentation (i.e., Sphinx) later.  To that end, let's use ReStructured Text throughout since that's what Sphinx uses.

-T

[Bjarni Ragnarsson]

Hi Travis and thank you guys all for your good work.

Based on my experience I would like to make a few suggestions. Mind
you, I only know so much and it's always so easy to point fingers
without having anything better to offer. I also might have missed out
something cause really Git and Github is a jungle. I've spent
countless hours going thru forks and branches trying to find the
"latest thing" and pretty much given up on it.
- My first suggestion is therefore to update the masters as frequently
as possible. It's fairly easy to clone :-)
- I've stumbled upon some docs scattered around. Getting them
together in one place would be a huge improvement. It doesn't have to
be fancy. Simple text files work like a charm. Just update
frequently.
- When writing docs, keep in mind that the readers don't know as much
as you guys about publishing, let alone the code. Some things might
be obvious to you but not the average reader like me.
- About the bug reporting system.... At this point an email address
(bu...@armstrongcms.com) would be great. At least there would be a
place to report bugs and perhaps offer solutions. A textfile with
unsolved bugs and solved would be great to in order to avoid
duplicates. Too fancy tools tend to create more problems than they
solve.

Suggestions on the docs.
- Installation is very simple and the docs (readme) explain the
progress. There might be some problems though in various systems -
especially related to virtualenv. I ran into problems with PIL in
ubuntu 11.04 for instance. One cannot cover everything.....
- Start from the end user and work from there. This also gives the
programmes the general idea. Focus on the core and essential
applications like articles and images.
+ Explain the end product. What does a web-publishing look like.
What are the elements in there. There are sections and columns in the
layout for instance. An image would help.
+ Explain the workflow in Armstrong. You write articles, upload
images and then what? You create wells and they are used to populate
columns?
+ Django templates and css. Where are they located.
+ Templatetags. What are the built-in templatetags and how are
they used. I really was expecting to find a render_well "type"
somewhere to put in the template to populate columns. But then again
- I really don't know how things are thought.
+ What is built-in and what needs to be programmed to make use of
the basic applications.

At this point one has the site up and running, able to put in data and
try things. Again - the demo is great. It needs expanding (I
strongly suggest including image handling) but a good starting point.
May I suggest perhaps showing how to list the latest articles on the
frontpage with a thumbnail and a summary?

What next.

- As a programmer I'd really like to see some hierarchy overview.
There are a lot of abstract classes, base classes, mixins and stuff
and for an outsider it's murder trying to figure out what gets done
where.
- What does an app need to interact with the core (render functions and such)
- What views does one need to write etc.

I think I'll stop here for now. Rome wasn't built in a day and at
this point I'd just be happy to have enough docs to understand the
basics so I can work my way from there and perhaps put in something
useful.

Best regards and again, many many thanks for your excellent work.
Bjarni.

[Niran Babalola]

Thanks for your feedback, which will be very helpful as we revise and
add documentation heading toward our initial release. If anyone else
has feedback along these lines, we'd love to hear it.

Niran Babalola
Director of Technology
The Texas Tribune
512-716-8699 — Office
775-576-4726 — Mobile
http://www.texastribune.org/

[Chuck Taylor]

Well, this installation is a little over my head but I'll try to figure it out. (You lost me at pip.)

I'm not going to be much help in documenting setup or configuration if command line is involved. I'd be better suited to explaining what Armstrong does once installed and how to work with it. If I'm able to get an installation up and running, I'll probably dive into that.

[Jan]

On Saturday, September 17, 2011 3:29:52 PM UTC+2, Bjarni wrote:

- When writing docs, keep in mind that the readers don't know as much
as you guys about publishing, let alone the code.   Some things might
be obvious to you but not the average reader like me.

I want to start using Armstrong when 11.12 is released. Since I'm pretty new at Django and Armstron I'll start documenting for myself anyway.

Since the Wiki is pretty empty I might as well start using the wiki. Usually I document with simple examples and fixes of problems I encounter. The glossary seems like a good place to start and I'll try to keep Bjarni's suggestions in mind. Maybe using the demo-site from
http://docs.armstrongcms.org/getting-started/30-seconds/ as a starting point.

It helps for me to understand the how and why before I can document something so when I do not grasp anything I will ask in this group.