Currently we have discussions regarding on how to deal with documentation. As we see it there are a few alternatives, and there are probably more that we haven't thought of. This post is hopefully the beginning of a discussion regarding how we are going to expose documentation for NodeStream.
drupal.org handbooks
Our current decision regarding documentation is to have it as handbook pages on drupal.org.
Positive
* Everyone can collaborate on the documentation
* Easy for non-technical users to contribute to the docs
Negative
* Hard to export
* Somewhat inaccessible to users in their actual NodeStream installation.
* A lot of people miss the documentation.
Advanced help
We could write our documentation as advanced help pages. This would make the documentation a part of the NodeStream repository.
Positive
* Easily distributable (HTML pages)
* Integrates with the actual NodeStream site in various ways.
* We can use advanced revisioning tools as it is part of the code repositories.
Negative
* Much harder for non-technical users to pitch in with documentation.
Some other solution
We could use a solution completely outside of Drupal for this. I can't come up with any candidates here, but please feel free to add them.
Comments
Nodestream Docs
Let Break things Down into smaller tasks.
Maybe we can come up with a few tasks to make it easier for people to create sections of documentation about nodestream
1. Installing nodestream
2. Better Formats
3. Nodestream Products
4. Nodestream Product views
5......and onwards
I agree, but that is much
I agree, but that is much more of a different issue, The main issue to discuss here is the basic method for doing the documentation, not the actual tasks for creating it.
//Fabian Sörqvist
Whoops I mean Dynamic
Whoops I mean Dynamic Formatters not Better Formats
However. I think we should do this all on D.O
In addition to using advanced help.
We can use drupal.org to provide an overview of what you need to know and then point users to advanced help for more specific documentation.
This way the drupal.org documentation can be kept quite general will require less updating
MediaWiki as a candidate outside of Drupal?
MediaWiki could be a candidate.
Positive
* Open Source
* LAMP installation
* A lot of third-party extensions
* Well documented API- & Hook- system that could be used to integrate with NodeStream. (Maybe a module that can be contributed back to the Drupal community)
* Exporting can be done in numerous ways
Negative
* Could be time-consuming to get it to fit NodeStreams needs.
My opinion is the keep all
My opinion is to keep all basic usage instructions in the advanced help and then link to a drupal.org handbook page for more advanced/developer documentation.
lslinnet is smart :)
lslinnet is smart :)
+1
This is the approach that the Rules project is taking right now, and I think it's a good one.
Over at http://drupal.org/node/1297414 there is a patch that shows one way of how this can be done, and still keep all the links in one place in the code – making it easier to maintain them, and also list on admin/help/nodestream.
//Johan Falk
External Help
Building on the stuff I wrote for the Rules module, I have now created a new module called External Help. The point of it is to make it easy to use and maintain links to external documentation pages within a module/project code.
In brief:
* A module declares all its external help pages using hook_externalhelp. This is placed in mymodule.externalhelp.inc.
* You can use externalhelp_url('module', 'topic') to retrieve the URL for help on a particular topic for a particular module.
* You can use externalhelp_url('module', 'topic', TRUE) to retrieve a ready-to-use help icon, linking to the external help page.
* You can use externalhelp_list('module') to get a list of all declared external help pages for a module, ready to use in hook_help.
I think this can be useful for NodeStream. Check out http://drupal.org/project/externalhelp for more information.
Help?
The description of this group was that it was a support group for people who are using nodestream. I'm using nodestream and I have tons of questions. It seems to me that getting some kind of documentation out there somewhere, anywhere, and quickly, would be most important. I usually prefer video. Seems like that would be easier than typing everything out anyway.
I'd really like to use this system, but I have a magazine to put out now. Where can I get help? Or should I just use a traditional drupal install and muddle through with a smaller system until nodestream is really ready to launch?
I like what I see. But I've been playing around with it and there's no description of well, anything. I have no idea how to use even the simplest things. Like what an article is and how to use it. How does it differentiate from a page? Why doesn't anything ever shows up in the sidebar. I've tried creating every type of content but nothing shows up in the sidebar. I looked into the panels and can't really figure out what will go there.
So a map of the panels of the site and how to get your information to pop up in those different panels would be great.
Also, the theme... I want to be able to alter the theme to meet my branding. I'm a web designer. I've been working with Drupal for about 2 yrs. I finally found the css files, and realized that the theme is actually two themes working as one... which is kind of a nightmare for designers. Still trying to determine if I can alter the css to meet my branding needs.
So I guess my question is... can I use this now? Should I wait? If I can use this now, is there any documentation other than that already on Drupal (which isn't very helpful for my needs).
Thanks
Help
Hi Tamela
Thanks for your comment
We are currently developing more documentation so you should have some more reference material soon.
To help you get going now here is some information.
The theme for Nodestream is a called a "Sub Theme" it is based on another theme a "Base theme" which is called Precision. This is quite a common practice in Drupal these days and can be useful if you are able to leverage the power of using sub themes and base themes together.
You can find out a little bit more information about it here. http://drupal.org/node/225125
As you mentioned Nodestream also uses panels, and page manager quite extensively. Hopefully we will be able to provide better information for this soon.
There is quite a bit of information on the Nodeone website http://nodeone.se/learn-drupal (Screencasts and tutorials) to help you understand panels and page manager if you have any question about it. The first Screencast in the series is here http://nodeone.se/node/782 to understand page manager.
Help?
Hi BJ & everyone,
Thank you for your help.
First, I want to make sure everyone knows how much I appreciate this project and what has already been done. It truly is amazing.
I looked over the links you sent. Unfortunately, I already knew how to use Pages and Page Manager. I had even taken the tutorial on nodeone for workbench. Drupal and its various modules is not my problem.
What I need is a visual of where all the pieces of the puzzle come together. A map, if you will. For example:
Since this is a pre-packaged solution, I assumed that the pages/panels were "preprogrammed" for specific types of content to be displayed in a particular way on the home page or blog pages. However, I may be wrong. Maybe it is not preprogrammed and I need to "program" the pages by creating my own variables or editing the content sections?
If so, I can do that. I was just under the assumption that it had already been done. I see that the blogs do have some organization already. They show up neatly on the blogs page.
If I do need to organize the other content myself, then having a map of what page templates control particular sections of the site could be very helpful. Especially because the enabled page templates have similar names. There is a template called Blogs. Then there is one called Node template that has two variants: Blog & Blog Post. That's three blog panel templates. I'm not clear on what each of them control. I could figure it out with a bunch of fiddling around, but it would be nice to have a map to spare newbies the extra time.
There are also several pages that have no variants. Several are not enabled. In order to know if I should use them, it would be helpful to know the structure of the site. Are things already set up? The video showed the site with columns and boxes for particular content. I don't want to start fiddling with the templates only to mess something up that already exists.
On a different note, here are some other questions:
I suppose this is the hard part of using a site that was set up by someone else. When I create my own, I know how I set it up structurally. When someone else sets it up, it is like wandering around in a maze created by someone else.
Finally, the video on nodestream demonstrates that you can have "edit regions" to move the articles around within a grid system from the home page. Those regions don't show up on my site. Do I need to activate something?
Thank you again for considering all my questions. I hope that my questions will help you when you are putting together your documentation. :-)
Tamela
OpenPub Map
Hi --
You're sure right about the need for a map.
As far as I can tell, most of it runs off the context menu, though I don't see how.
Have to go to work, later,
Kirk B.