|
1) Prefer one long article
2) The article broken apart into logical parts
3) Don't care as long as it has links to the other parts
4) Don't care, won't read anyways
Nothing to do with JSOP's post, it's something I've been mulling over as I have an article that in Word (and there's only 5 or so screenshots) is over 120 pages.
The topic is a C# implementation of Kademlia.
|
|
|
|
|
Break the sucker up: or it'll get hammered by the TL;DR brigade.
It does need to be in relatively "bite sized" chunks - that's why books have chapters - and it's always nice to have the relevant logical parts together rather than having to hunt and hope you didn't miss anything important.
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
OriginalGriff wrote: Break the sucker up
Well, that'll increase my article count. 
It'll be interesting doing that, as currently I have in each section things like "discussion", "implementation", and "unit tests" for each functional component. That might make for a logical break. There's also a GUI demo, which makes sense to keep separate.
Thanks for the feedback!
|
|
|
|
|
Has anyone ever had all the places in the "Article of the month" competition yet? 
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Orig
It does need to be in relatively "bite sized" chunks - that's why books have chapters - and it's always nice to have the relevant logical parts together
I concur with you, with a few caveats:
- All of the pieces are published within a short period of time.
- The author(s) has had other proofread the entire series, as a whole. The tone, tense, voice, word use, and style should be consistent for the entire series. This is especially important for authors who, like most engineers, did not pay attention during their English Comp. courses. (Many people I've worked with cannot write a decent, error-free one-page memo. English is their primary and, often, only language, yet I shudder to think of them writing a five-to-ten page paper!)
- They include a table of contents (and maybe an index)
- Figures, charts and other inclusions are labeled and numbered.
- The author takes care to define acronyms and unusual technical terms upon first use. We all know what delegates are, what MVVM and FPGA stand for, and how to implement a decision table via linkage editor, right?
- The author(s) cite their source material. If they say they adapted Erin Katzenjammer's technique, please tell us where we can find Katzenjammer's article on the subject. A good hot link is enough. (See The Katzenjammer Kids[^].)
Maybe, I am asking for too much....  We are talking about engineers and programmers, after all...
__________________
Lord, grant me the serenity to accept that there are some things I just can’t keep up with, the determination to keep up with the things I must keep up with, and the wisdom to find a good RSS feed from someone who keeps up with what I’d like to, but just don’t have the damn bandwidth to handle right now.
© 2009, Rex Hammock
modified 29-Sep-17 11:54am.
|
|
|
|
|
Jalapeno Bob wrote: Many people I've worked with cannot write a decent, error-free memo.
I run my articles through MS Word now. That catches most of the outright incorrect spellings, but misses the words that are spelled correctly, yet are the wrong word, or incomplete give the sentence structure. It's not perfect, but it catches a lot of crap.
I edit the article in a HTML file in Visual Studio, and then copy/paste that into MS Word, fix the glaring problems, and then paste it back into the HTML file.
Jalapeno Bob wrote: All of the pieces are published within a short period of time.
I do all parts of a multi-part article at the same time. This keeps me from procrastinating on finishing subsequent parts.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
John Simmons / outlaw programmer wrote: I edit the article in a HTML file in Visual Studio
Heh, I still use FrontPage. It does spell-checking. 
|
|
|
|
|
There's two different moments where I'm reading articles; first, there's just staying up-to-date, reading about new and interesting things. For these I prefer not too long articles with some pictures as a short introduction into a framework or idea.
Other moments I'm implementing something and get stuck. In that case I don't care about the length, I care more about the code-examples and the headlines. Any (sub)title will indicate whether or not this is similar to what I'm trying. Depending on the situation and severity, the article moves to the second monitor, or is printed entirely.
120 pages is more in the realm of "book" than it is an "article". I seriously would not mind seeing a new category called "books", especially if I could PDF it onto the e-reader.
Bastard Programmer from Hell 
If you can't read my code, try converting it here[^]
|
|
|
|
|
I usually prefer one long article.
But 120 pages seems to be quite large. If the article can be split into self-contained sections I would place them on their own pages.
Links to the previous and next page on top and bottom are a must for me. A link section to all pages should be on top of the first page and optionally on the other pages.
|
|
|
|
|
Think about it this way... when reading a technical document, do you prefer to read it on the screen or do you print it?
Does the number of pages affect your decision?
Now, treat an article the same way.
|
|
|
|
|
IMHO, #2 should always be the case as it makes for easier readability.
I also recommend breaking up the article into separate articles since you say it's more than 120 pages in length.
/ravi
|
|
|
|
|
|
Below is an example from Bloomberg.com (Bloomberg Business mag) that may help you. It is also an interesting angle on what code is and what devs do.
The points here are:
1. this is a long article
2. it is a very well-written article.
3. I was interested in the article but the length still made it extremely overwhelming.
4. the author uses all kinds of interactive techniques in the article and it still feels overwhelming.
5. the author is a professional writer and the length is still almost like a blunt weapon on the brain
Paul Ford: What Is Code? | Bloomberg[^]
So, my answer, -- even though I break it myself -- is break it up into parts.
Great question, by the way.
|
|
|
|
|
If you've already written the article, and don't feel like breaking it up into a series of smaller articles, you could add a table-of-contents at the top, which allows the user to click a link to take them to the various chapters. At each chapter, you can also add a "Back to top" link that lets them return directly to the TOC again.
However, the less observant retard reader won't notice these features, and will still dog on you for writing such a long article. It seems people's attention spans are getting shorter every day, and just "wants da codez".
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
What about
5) CodeProject provides a mechanism whereby authors can specify page breaks which allows readers to view it in one piece or page-by-page.
cheers
Chris Maunder
|
|
|
|
|
Oooohhh, I like that one.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
|
If you do that, please have a way to have distinct URLs per page. So you can link to a specific page from an external site.
|
|
|
|
|
Definitely
cheers
Chris Maunder
|
|
|
|
|
Chris Maunder wrote: CodeProject provides a mechanism whereby authors can specify page breaks which allows readers to view it in one piece or page-by-page.
That would be cool. Plus an "e-book" section.
|
|
|
|
|
#2
#SupportHeForShe
Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson
You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
|
|
|
|
|
Consider releasing it as a book 
|
|
|
|
|
Sander Rossel wrote: Consider releasing it as a book
I've contacted SyncFusion.
|
|
|
|
|
I only look at the photos...
(reverse playboy reference here).
I'd rather be phishing!
|
|
|
|
|
Maximilien wrote: I only look at the photos...
That's how I used to read Scientific American. The articles in Hefner's mag were much better.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
