standardizing page names on the wiki
Joe Johnston
our links don't break. Hooray! Well, this at least means more than
one person is editing the wiki. Yet another milestone of sorts
reached.
Currently, there are a lot of broken links pointing to the old
pdxproject.pbworks.com wiki. This is because I moved the wiki URL to
projectnori.pbworks.com. This also exposed an issue with most of the
current pages in the wiki: page names are really long and easily
broken in links. It will be easier to tweak things now before people
start linking to our docs.
As a general rule, keep wiki slugs (URLs) as short as possible and
name them something that's more about the concept of the page rather
than the verbatim text of the incoming link.
For instance, we have a lot of pages named with a question mark or
other punctuation.
Instead, this page should probably be named something like "PDS XDI
Endpoint Discovery". Incoming links can be different text from the
page name. The most important thing is to make the page names as
simple as possible so they can stand the test of time.
If anyone has time over the weekend, please go through the wiki and
rename the pages to name that are a bit more permanent. Don't worry
about breaking incoming links. We'll sort that out later.
Cheers,
Joe
--------------------------------------------------------------------------------
Joe Johnston
http://www.simple10.com
--------------------------------------------------------------------------------
Markus Sabadello
Moving from pdxproject.pbworks.com to projectnori.pbworks.com is okay.
Regarding the long wiki page names with punctuation, the reason for this is that the Dev: Topics page (which apparently you renamed to FAQ - not a good idea I think, because it's about tech topics, not a general FAQ) consists of a list of questions, and I wanted those questions to be consistent with the headings on their corresponding wiki pages.
For example, one of the questions is
How can a PDS XDI endpoint be discovered from a user’s identifier(s)?
If you click on the link (assume the link wasn't broken, which is the case now), then you come the following page, which has the same title as the link you just clicked on:
http://projectnori.pbworks.com/How-can-a-PDS-XDI-endpoint-be-discovered-from-a-user%27s-identifier%28s%29
If the page had another heading such as "PDS XDI Endpoint Discovery", then that would be less consistent and more confusing.
Therefore, I proposed we keep the existing practice.
Note that we only have these long page names for questions on the Dev: Topic / FAQ page.
For all the other wiki pages, we DO have shorter names, e.g.:
http://projectnori.pbworks.com/PDS-Weekly-Retreat
http://projectnori.pbworks.com/PDS-Dev-Plan
Markus
Joe Johnston
The entire Project Nori site is tech related which is why I renamed
"Dev: Topics" to FAQ. Plus, we can now add additional Q&As on the
page that are less technical if needed.
General best practices for FAQs is to follow a Wikipedia style layout
with a table of contents (the questions) at the top of a page linking
to short answers on the same page. The answers then link off to
relevant documentation as needed. This makes maintaining
documentation much easier in the long run since content only exists in
one place (the main doc page for a given topic) and is summarized and
linked to from other pages (like a FAQ). It also allows for the
rewording of the questions without breaking links.
Examples:
http://docs.python.org/faq/general
http://httpd.apache.org/docs/1.3/misc/FAQ.html
We probably also want to avoid putting "UNDER CONSTRUCTION" on pages.
It's kind of a red flag of sorts in the web 2.0 community. General
rule is to not create a page until content is available. Less is more
when it comes the to number of pages. If needed, put a note at the
top of a page like "this page is in development and currently only
contains a high-level overview." Minor difference, but it goes a long
way.
Cheers,
Joe
Markus Sabadello
First, I don't think it's true to say that the entire site is / will be tech related.
Second, the "Dev: Topics" page was intended to be a knowledge base kind of thing (think MSDN) rather than an overview FAQ. It will potentially have many many questions at various detail levels, and it will directly link to the authoritative wiki pages with the long answers, rather than provide a high-level FAQ-style answer. Your point of "content existing only in one place" is precisely what I was aiming for. With a classic FAQ-linking-to-other-pages, that wouldn't be the case.
I totally agree with you on the "under construction" pages. Most of the unanswered questions so far don't actually have pages yet, which is better than having "under construction" pages. For those pages that DID say "under construction", I just changed that by adding quick answers.
Markus
Joe Johnston
technical reference documentation on the wiki. It probably makes
sense to also move the code component page (pds-core, pds-core-xri,
etc.) to the wiki. This will make it easier for others to add
components without needing a wordpress account on projectnori.org.
Sound good?
Cheers,
Joe
On Sat, Oct 2, 2010 at 1:15 PM, Markus Sabadello
Markus Sabadello
Not sure whether the list of questions ("Dev: Topics" or "FAQ" ..) should be on the site or the wiki. It might look nicer on the site, but it would be easier to edit on the wiki..
Yes the code components should probably also be moved to the wiki.
We could have a component overview page that says the following about each component:
- Short description
- Link to documentation wiki page
- Link to source code
- Language and Packaging (.jar, .war, Python, ....)
I like the way Higgins is doing it:
http://wiki.eclipse.org/Components_1.1
Markus
Joe Johnston
I'll keep working on the top nav pages this week as time allows and
leave the code pages to you.
Cheers,
Joe
On Mon, Oct 4, 2010 at 1:33 PM, Markus Sabadello