Feedback on ReadmeFirst

As a new TWiki Admin I felt it would be naughty to even read in Codev (they keep logs, you know!!) much less write anything there.

As time went on, I saw more and more links to Codev from answers in Support, and I wondered why these essential TWiki-saving gems were hidden away from plebs like me.

Then curiosity won over politeness, and I boldly browsed through a wealth of information that transformed my TWiki and my understanding of its workings into something more than a fun toy, into something very useful to hundreds of staff at work. I was neither willing nor able to do anything to assist at that time, still busy trying to get my own system working and find out if I'd keep using TWiki or not, so according to the docco I shouldn't be snooping around Codev, but I hoped that carefully disguised as TWikiGuest I wouldn't be found out.

Many months later I'm the resident opinionated blabbermouth TWiki Admin. Although I don't code and I'm not likely to start at my age, I now regard Codev as my primary reference on administering TWiki, because most of the essentials and all of the gems are in there. Who knows, I might even blurt out something useful one day.

Looking back on ReadmeFirst and WebHome I can see that it says I was welcome last year, but I was too insecure to see that then. Maybe it's good like that, to discourage people from using Codev when they should use Support, but the fact is that before inviting myself into Codev I was only using 30% of the features TWiki offers.

Now I see Codev as performing two separate roles: all those things that it is for developers, and a reference resource for Admins tweaking and advocating and squeezing the most out of their basic TWiki installations. I'm not proposing any change or no change, simply pointing out a new admin's impressions. There's a lot of topics that aren't about developing something but about utilising what we downloaded.

So no, ReadmeFirst doesn't tell it to me like it is, and it took a long time to find out by peeking into "other people's business". I don't think it can do much better though, because Codev is at least one whole web more than a place for coders.

By the way, I noticed two appealing links on WebHome called TWiki Reference Manual and TWiki User's Guide but they both just link to TWiki. You big teaser! Maybe that's a hint?

-- SueBlake - 05 Aug 2003

On coding convention and white space:

• Suggestion: Do not use tabs at all in this case. Mixing tabs and spaces often causes problems, but even more so when you are accepting (or creating) patches. If the contents of a patch file is copied&pasted into a page then you instantly lose all tab information, and the same often goes when merging large patches (specifically rejections) by hand. This has caused a number of issues in reducing the size of the MegaTWiki patch to something reasonable.

-- MS - 10 Jan 2004

This is a good suggestion, amended ReadmeFirst accordingly.

-- PeterThoeny - 05 Aug 2003

On the workflow for release in ReadmeFirst: I suppose this workflow also applies to the Subversion source control nowadays. Maybe it could be updated to reflect the current procedure?

-- RasqualTwilight - 12 Aug 2005

On TWiki Coding Conventions and pod declarations:

The coding conventions are most well done, but they seem to omit an explaination of the pod declarations "=begin twiki" and "=end twiki" located in the twiki/lib/ Perl scripts. If nothing else it begs the question: is there a pod2twiki tool somewhere in the release that I've missed?

Example from TWiki.pm:

=begin twiki

---+ TWiki Package
This package stores all TWiki subroutines that haven't been modularized
into any of the others.

=cut

-- BillKanawyer - 27 Oct 2005

See PerlDocPlugin.

-- PeterThoeny - 05 Jan 2007

Scanning through ReadmeFirst with interest an coding, the first several items of How to Contribute lead one to believe (if you're scanning through it) that the How to Contribute section has nothing to do with coding, since it starts with a bunch of peripheral things like sharing your story, being a support god, and contributing brainpower. Then the last two items on the list are actually about coding and this important link is buried there: SoYouWantToBeATWikiDeveloper.

I like the layout of the page, I just think I would split the top section into two: How to contribute in peripheral ways, and how to get started coding... either split it using two subsections or just give the coding section it's own header. And I would also emphasize the link mentioned above with a full title listed to make it easy for people to find. For example,

If you're interested in contributing code, please see SoYouWantToBeATWikiDeveloper - Help on getting started as a TWiki developer.

-- JoshuaJohnston - 05 Jan 2007

Joshua: Godd feedback. We suffer from déformation professionnelle; fresh blood is good. Please go for it and make the changes, this is a wiki where nothing gets lost.

-- PeterThoeny - 05 Jan 2007

Joshua has a good point, it's a tricky balance between promoting the two kinds of contributions and making all feel valued. But I'm pleased to see that my (mostly) non-coding efforts have not actually been referred to as "peripheral". This warm welcome and suggestions for what can be done by anyone at all, is one of the important things that caused me to hang around Codev and contribute occasionally.

The page looks pretty good to me now, but there's always room for improvement and fresh perspectives.

-- SueBlake - 07 Jan 2007

It's been suggested my question in Support web (IsThereAWikiFormatControlForNewLine) would be better suited to Codev. It's about requesting a 'simple' enhancement to formatting rules to allow for new lines. However, I certainly don't have the time to contribute a change and probably not the skill, but I can't see where I should make the suggestion.

-- DavidFerrington - 21 Mar 2007

Fresh perspective - See Jef Raskin's summary of the design rules in his user inteface book at http://Nitpicker.PBwiki.com/The+Humane+Interface and compare them with the top of the ReadmeFirst page. One rule is not to make me do more work than is necessary to get the job done. This is a fairly trivial point in this case. When I get this text box, after asking for it, the cursor is not in the bos. In fact, the box is not even visible, most often. But it could be.

Further, any substantial comment will overflow the box and make it harder to proofread the content and get it right.

Adding Jef's rules to the sensible ones you already have would improve the set. At least, that's what I think.

-- RichardKarpinski - 05 May 2008